execution contract #2475
execution contract #2475
Conversation
prepared an execution contract draft Signed-off-by: Dan Calavrezo <[email protected]>
dcalavrezo-qorix
requested review from
AlexanderLanin and
MaximilianSoerenPollak
as code owners
|
|
|
The created documentation from the pull request is available at: docu-html |
AlexanderLanin
left a comment
AlexanderLanin
left a comment
There was a problem hiding this comment.
Lots of comments, but this was a great read! Good content IMHO!
| - Tools affecting build outputs must either be: | ||
| - managed by Bazel, or | ||
| - explicitly injected as Bazel action inputs, or | ||
| - reflected in cache partitioning |
There was a problem hiding this comment.
not sure what you mean here. Theoretically its enough if they are documented as in R2, but of course we want more.
What about "mirrorable"... no idea how to describe it. I'm talking about pypi for example.
| - managed by Bazel, or | ||
| - explicitly injected as Bazel action inputs, or | ||
| - reflected in cache partitioning | ||
| - Reliance on host state must be minimized and documented where unavoidable. |
There was a problem hiding this comment.
This is not the same indentation as above. So "Tools affecting build outputs must either be...documented" is missing?
| Build actions must not depend on **undeclared inputs**. | ||
|
|
||
| In practice: | ||
| - Tools affecting build outputs must either be: |
There was a problem hiding this comment.
Let's explain "Tools affecting build outputs" to be very clear. With example of such tools. And tools that are less relevant.
e.g. I'm currently not sure whether pytest affects build outputs. Are test results build output?
There was a problem hiding this comment.
Test results are not build outputs, but they do affect CI decisions ( I guess quality gates) so the tools that produce them must still be Bazel-visible if you want correctness, reproducibility and traceability.
Theoretically we should use Bazel Pythong rules ( rules_python). This would ensure:
- Reproducible test outcomes
- Correct test caching
But I guess it is an acceptable fallback to have Pytest installed in the devcontainer.
Do we have a file like a fingerprint.txt which contains the versions of the tools?
pytest==7.4.2
python==3.11.6
container=sha256:deadbeeeeeeeeef.......
That one can be used as an input for the test action. That way Bazel sees when the fingeprint changes and it can invalidate the caches accordingly
|
|
||
| ## Three-Layer Execution Contract | ||
|
|
||
| ### Layer 1 — Host Platform Contract |
There was a problem hiding this comment.
x86, arm for Macs would also belong to host?!
There was a problem hiding this comment.
Good point
There was a problem hiding this comment.
But I've no idea what's the correct list of supported archs for hosts. Who could help clarify this?
| - Provide consistent runtime ABI (`glibc`, `libstdc++`) | ||
| - Ensure tool binaries (e.g. rustc) can execute reliably | ||
| - Eliminate “works on my machine” discrepancies | ||
| - Enable local reproduction of CI builds |
There was a problem hiding this comment.
We need to figure out what exactly has to be identical. Or is it this list?
e.g. devcontainer is based on Ubuntu 24. GitHub Runners are based on Ubuntu 24. Is it now enough to ensure the same python version for python scripts?
There was a problem hiding this comment.
you can specify at Github Action Workflows that a specific container image and version shall be used: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontainerimage
Then there is no fingers crossed anymore if CI and devcontainer have the same tools and versions installed.
| --> | ||
|
|
||
|
|
||
| # DR-001-Infra-Extension: S-CORE Build Execution Contract |
| This layer defines **what Bazel controls and guarantees**. | ||
|
|
||
| #### Bazel Versioning | ||
| - Each repository must contain `.bazelversion`. |
There was a problem hiding this comment.
not every repository is using bazel... well, again it depends on which repositories are relevant here.
| ## Minimum Supported Baselines | ||
|
|
||
| ### OS and Runtime Baseline | ||
| - Minimum supported baseline: **Ubuntu 20.04 LTS** (subject to revision) |
There was a problem hiding this comment.
Baseline is defined in layer 2. So layer 3 should not mention an exact version?
| ### Rationale | ||
| We explicitly do **not** support all historical `glibc` or kernel versions. | ||
| Portability is achieved by choosing and documenting a baseline, not by unlimited | ||
| backward compatibility. |
There was a problem hiding this comment.
| backward compatibility. | |
| backward compatibility. Layer 2 can easily be virtualized as needed, for future reproducibility. |
Co-authored-by: Alexander Lanin <[email protected]> Signed-off-by: Dan Calavrezo <[email protected]>
|
|
||
| In practice: | ||
| - Tools affecting build outputs must either be: | ||
| - managed by Bazel, or |
There was a problem hiding this comment.
The writing here suggests that if it's managed by bazel it then automatically is solved and we don't need to worry about it anymore.
Is that the case, or am I miss-reading here?
There was a problem hiding this comment.
I have doubts about that. bazelisk downloads even bazel from the Internet, which then might download more dependencies.
|
|
||
| #### Non-Goals | ||
| - The devcontainer must **not silently override** repository-declared Bazel versions. | ||
| - The devcontainer must **not be the only place** where critical tool versions are defined. |
There was a problem hiding this comment.
Where else would you define it then? In a global ledger or so?
| - versioned | ||
| - immutable | ||
| - built against a documented baseline | ||
| - Tools affecting outputs must be known to Bazel or reflected in action inputs. |
There was a problem hiding this comment.
Outputs in which way?
Does this mean for example if something saves a .json that is used as cache it should only work via Bazel actions?
Or what about the test frameworks that can affect the output xml?
|
Thanks for the write up, looks over all quite good and a great baseline we can work out the small other stuff. |
| - Provide consistent runtime ABI (`glibc`, `libstdc++`) | ||
| - Ensure tool binaries (e.g. rustc) can execute reliably | ||
| - Eliminate “works on my machine” discrepancies | ||
| - Enable local reproduction of CI builds |
There was a problem hiding this comment.
you can specify at Github Action Workflows that a specific container image and version shall be used: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontainerimage
Then there is no fingers crossed anymore if CI and devcontainer have the same tools and versions installed.
| #### Responsibilities | ||
| - User-space runtime libraries | ||
| - Bootstrap tooling (git, bash, coreutils, python, etc.) | ||
| - Bazel entrypoint (preferably Bazelisk) |
There was a problem hiding this comment.
I am a bit puzzled. IIRC Bazelisk transparently downloads whatever bazel version has been specified via .bazelversion from the internet. How will this ensure stable builds in like 10+ years? We have no guarantee that the server address is still the same and the version still available.
| This must remain possible even if: | ||
| - GitHub runner images change or are retired | ||
| - upstream toolchains are no longer available | ||
| - external services are unavailable |
There was a problem hiding this comment.
should we have a test build, which has no access to the internet? This way we can be sure all needed tools and code are present.
| #### Definition | ||
| - A **versioned devcontainer image** is the default execution context. | ||
| - The container image must be: | ||
| - built from a known OS baseline (Ubuntu LTS) |
There was a problem hiding this comment.
we should keep in mind that Microsoft removed support for older Ubuntu versions running in devcontainers from Visual Studio Code. Thus if your devcontainer image is based on Ubuntu 18.04, you are at the moment only able to run it via command line.
No description provided.